home *** CD-ROM | disk | FTP | other *** search
/ APDL Eductation Resources / APDL Eductation Resources.iso / programs / electronic / rlab / !RLaB / help_a_i / getline < prev    next >
Encoding:
Text File  |  1995-02-04  |  3.4 KB  |  107 lines
  1. getline:
  2.  
  3. Syntax:    getline ( FN )
  4.     getline ( FN, LL )
  5.  
  6. Description:
  7.  
  8.     Getline returns an N-element list which contains all of the
  9.     tokens from a line in the file described by FN. The tokens are
  10.     delimited by whitespace. Numbers are installed in the list as
  11.     numeric scalars, everything else is installed as scalar
  12.     strings.
  13.  
  14.     The list elements have numeric indices, and are numbered from
  15.     1 to N. The 1st element containing the 1st token on the line,
  16.     and the Nth element containing the last token on the line. The
  17.     newline is not returned as a token.
  18.  
  19.     Getline will also recognize everything enclosed within a pair
  20.     of `"' as a string, including escape characters.
  21.  
  22.     Getline will always return a list-object. When an empty-line
  23.     has been read, getline returns an empty list. Getline will
  24.     terminate on an End-Of-File (EOF).
  25.  
  26.     The filename can be a string that specifies a sub-process (see
  27.     `help FILES'), in which case getline() will run the
  28.     sub-process, and read from the process's standard output.
  29.  
  30.     The second, and optional argument, LL, forces getline to
  31.     return the entire line as a string, without any parsing. If LL
  32.     is <= 0, then getline will read lines as long as 512
  33.     characters. If LL > 0, then getline will read lines as long as
  34.     LL characters. The return value is a single string, not a
  35.     list, when LL is used. If getline encounters and EOF, while LL
  36.     is being used, a numeric value of 0 is returned.
  37.  
  38.     Examples:
  39.  
  40.     To get input interactively:
  41.  
  42.     > printf( "Enter a string and a number: " ); x = getline( "stdin" );
  43.     Enter a string and a number: test-string 1.234e5
  44.     > show(x)
  45.        name:   x     
  46.        class:  list  
  47.            n:  2     
  48.     > x.[1]
  49.     test-string
  50.     > x.[2]
  51.      2 =
  52.      1.23e+05
  53.  
  54.     Given a file named `test', which contains the following lines:
  55.  
  56.     jcool  259  4 1075  822 vt01     S   Dec 29  9:32 X :0 -p 1 -s 5 
  57.     jcool  256  0   21    0 console  S   Dec 29  0:00 startx 
  58.     jcool  261  0  338   88 console  S   Dec 29  0:16 twm 
  59.     jcool  288  8  635  333 ?        S   Dec 29  2:00 emacs 
  60.     jcool  287  0  408   65 console  S   Dec 29  0:01 xclock 
  61.     
  62.     tmp = getline( "test" );
  63.     
  64.     would produce a list variable named `tmp' with 16 elements:
  65.     tmp.[1] would be the string "jcool" and tmp.[16] would be the
  66.     number 5.  The next call to getline() would read the second
  67.     line in the file, and create a new list containing those
  68.     elements.
  69.  
  70.     The above could also have been done with:
  71.  
  72.     tmp = getline( "|ps -aux | grep jcool" )
  73.  
  74.     Which would open a readable pipe to the "ps -aux | grep jcool"
  75.     command and grab a line at a time from the process.
  76.     
  77.     To read the entire contents of a file:
  78.  
  79.     if (length (ans = getline("stdin"))) 
  80.     { 
  81.       // do something with ans
  82.     else
  83.       // finish up
  84.         }
  85.  
  86.     Since getline returns an empty list when there is no input, we
  87.     can tell when to terminate the input loop by checking the
  88.     length of the returned list.
  89.  
  90.     Using the optional second arguemnt to getline we can get
  91.     old-style Fortran formattted output. For example, we have a
  92.     file filled with:
  93.  
  94. 0.1285186E+000.1463163E+000.0000000E+000.0000000E+000.0000000E+000.0000000E+00
  95. 0.0000000E+000.0000000E+000.0000000E+000.0000000E+000.7322469E-010.5245288E-01
  96. 0.0000000E+00-.9399651E-010.2397120E-01-.6551484E-010.2616772E+020.5796479E-01
  97. 0.0000000E+000.2500000E+000.7788281E-010.2121489E-010.0000000E+00-.1345507E+00
  98. 0.1516225E-01-.1284981E+000.1136876E+020.3010250E-010.0000000E+00-.2500000E+00
  99.  
  100.     we can do:
  101.  
  102.         lv = strtod (getline (FN, 13));
  103.  
  104.     and get a vector with the numeric values for each line.
  105.  
  106. See Also: FILES, LIST
  107.